QuickTime 4 Reference

Creating a Sample Description

It is important to distinguish between the sample description and the effect description. The sample description is a data structure that describes a sample of a track's media. The effect description is the sample that is being described in this case.

To create a sample description, you create and fill out a data structure of type ImageDescription . QuickTime 4 introduces a new function, MakeImageDescriptionForEffect , that simplifies this process.

Important
Only image descriptions made with MakeImageDescriptionForEffect can be used in stacked effects, where one effect track acts as a source for another. Image descriptions built for effects using sample code from earlier versions of QuickTime cannot be used when stacking effects.

Listing 3 Creating and filling out a sample description



 
ImageDescriptionHandle QTEffects_MakeSampleDescription 

    (OSType theEffectType, short theWidth, short theHeight)



{

    ImageDescriptionHandle mySampleDesc = nil;

    OSErr myErr = noErr;



    // create a new sample description

    myErr = MakeImageDescriptionForEffect(theEffectType, &mySampleDesc);

    if (myErr != noErr)

        return(nil);



    // fill in the fields of the sample description

    (**mySampleDesc).width = theWidth;

    (**mySampleDesc).height = theHeight;



    return(mySampleDesc);

}

The ImageDescription data structure is described in detail in Chapter 4, "Image Compressor Components."

The parameter theEffectType specifies the effect, and the parameters theHeight and theWidth specify the height and width of the effect's visual output in pixels.

Note
If the specified effect component is not available when the sample is decompressed (that is, when the movie containing the effect track is run) an error occurs.